Matrix-Account-Registrierungen mit Token absichern

Ich habe mich lange geärgert. Des öfteren wollten Freunde von mir ein Konto auf meinem Matrix-Server anlegen – aber ich hatte die Registrierung aus Sicherheitsgründen deaktiviert. Also musste ich die Accounts manuell anlegen.
Offene Registrierungen laden leider Spam und Bots ein, und das wollte ich meinen Räumen nicht antun.

Mit einer kleinen Ergänzung in meiner homeserver.yaml habe ich Synapse jetzt aber um eine richtig praktische Funktion erweitert: sichere Registrierungen mit Token. Und das Beste: ich kann Tokens sogar direkt per Matrix-Nachricht abrufen.

Ich habe beim Dominik (👉 ztfr.de) zufällig gesehen, dass er die Registrierung mit Token schon eine Weile einsetzt. Daraufhin habe ich ihn gefragt und er hat mir die Grundkonfiguration gezeigt – vielen Dank an dieser Stelle! 🙂
Auf dieser Basis habe ich mich dann noch ein wenig weiter eingelesen und bin schließlich auf die Möglichkeit mit Maubot gestoßen, die das Ganze für mich noch komfortabler macht.

⚙️ Die Synapse-Konfiguration

Die Konfiguration in der homeserver.yaml ist überschaubar:

# Registration
enable_registration: true
registration_requires_token: true
registration_shared_secret: "zensiert"
token: "ein-selbstgewaehlter-token"
enable_registration_without_verification: false
bcrypt_rounds: 12
registrations_require_3pid:
  - email

Hier die einzelnen Punkte erklärt:

• enable_registration: true → Schaltet die Registrierung frei.
• registration_requires_token: true → Neue Nutzer brauchen ein gültiges Token.
• registration_shared_secret → Wird für Skripte genutzt, um Accounts automatisiert zu erzeugen (nicht für normale Nutzer).
  (Hinweis: Diese Variable wird bereits bei der Installation von Synapse vordefiniert. Prüfe also, ob sie bei dir bereits konfiguriert ist. Ein zweiter Eintrag ist nicht nötig.)
• token → Ein selbstgewählter fester Token. Funktioniert, ist aber unsicher, wenn er bekannt wird.
  (Wird nur benötigt, wenn der Token nicht per API (Maubot) erzeugt wird, siehe unten.)
• enable_registration_without_verification: false → Setzt voraus, dass E-Mail-Verifizierung genutzt wird.
• bcrypt_rounds: 12 → Stärke des Passwort-Hashings, 12 ist ein guter Wert.
• registrations_require_3pid: – email → E-Mail-Adresse muss verifiziert werden. Achtung: nur nutzen, wenn der Mailversand vom Server funktioniert.

Wenn man den festen Token nutzt, ist die Einrichtung hier schon abgeschlossen. Danach reicht ein Neustart von Synapse.

Besser ist allerdings der Weg über die Synapse-API – damit können Tokens zeitlich begrenzt oder auf eine bestimmte Anzahl von Registrierungen beschränkt werden.

🤖 Token-Verwaltung per Maubot

Noch komfortabler wird es, wenn man Tokens direkt per Matrix-Bot verwalten kann. Ich habe das mit Maubot umgesetzt. Voraussetzung ist eine Maubot-Manager-Instanz. Wer dazu Infos braucht: die offizielle Doku gibt es hier → Maubot Setup. Falls Interesse besteht, kann ich dazu auch mal einen eigenen Beitrag schreiben – einfach einen Kommentar hinterlassen!

Das passende Plugin habe ich hier gefunden: maubot-token auf GitHub. Dort gibt es die .mbp-Datei direkt in den Releases.

🔧 Plugin installieren und konfigurieren

Die Installation im Maubot-Manager geht schnell:

• Im Webinterface bei Plugins auf das Plus klicken und die .mbp-Datei hochladen.

• Unter Instances eine neue Instanz anlegen, eine ID vergeben, auf Enabled und Running stellen.
• Den gewünschten Bot-Account als Primary User auswählen.
• Plugin-Typ auswählen und speichern.

Anschließend öffnet sich die Konfiguration. Meine sieht so aus:

# Access Token of any Admin
access_token: 'MDAxOGxvY2F...SECRETVALUE...'
# Base Url for Synapse admin API
admin_api: http://matrix-synapse-app:8008/_synapse/admin
# Base command without the prefix (!).
base_command: token
# Default allowed uses per token
default_uses_allowed: 1
# Default expire time per generated token 7days=604800s
default_expiry_time: 604800
# Wer den Bot nutzen darf
whitelist:
- '@patrick:techniverse.net'

Erklärung der Konfig:

• access_token → Admin-Token deines Synapse-Servers (Achtung: sicher verwahren!).
• admin_api → URL zur Admin-API. Beispiel: http://matrix-synapse-app:8008/_synapse/admin.
• base_command → Welches Kommando genutzt wird (!token).
• default_uses_allowed → Wie viele Registrierungen ein Token standardmäßig erlaubt.
• default_expiry_time → Lebensdauer in Sekunden (604800 = 7 Tage).
• whitelist → Nur diese Benutzer dürfen den Bot steuern. Sehr wichtig!

Einen Access Token für den Bot erstellen:

Damit der Bot mit der Synapse-Admin-API sprechen kann, brauchst du ein gültiges Access Token eines Admin-Accounts.

Diesen kannst du ganz einfach mit curl abfragen:

curl -XPOST \
  -d '{"type":"m.login.password", "user":"servicebot", "password":"geheimespasswort"}' \
  "https://matrix.techniverse.net/_matrix/client/r0/login"

Parameter erklärt:

• type: Gibt die Login-Methode an (m.login.password = Benutzername/Passwort).
• user: Der lokale Benutzername (z. B. servicebot). Ohne @ und ohne Domain.
• password: Das Passwort des Accounts.
• URL: Dein Matrix-Server, hier im Beispiel https://matrix.techniverse.net.

Die Antwort sieht in etwa so aus:

{"user_id":"@servicebot:techniverse.net","access_token":"MDAxOGxvY2F...SECRETVALUE...","home_server":"techniverse.net","device_id":"ZRRLKCIQIC","well_known":{"m.homeserver":{"base_url":"https://matrix.techniverse.net/"}}}#

Den Wert von access_token kopierst du und trägst ihn in die Konfiguration des Plugins ein (access_token: 'MDAxOGxvY2F…SECRETVALUE…').

Damit ist dein Bot startklar und kann Tokens per Chatbefehl erzeugen. 🎉

💬 Nutzung im Matrix-Raum

Danach habe ich einen Raum erstellt und den Bot, den ich oben festgelegt habe, eingeladen.
Einfach den Befehl !token eingeben und schon zeigt er die Hilfe an:

Usage: !token <subcommand> [...]

list [token] - List all [or specific] Tokens
generate [uses] [expiry] - Generate a Token
delete <token> - Delete a Token

Befehle im Detail:

• list [token] → Zeigt alle Tokens an. Beispiel: !token list
• generate [uses] [expiry] → Erzeugt ein Token. Beispiel:
  • !token generate → 1 Nutzung, 7 Tage gültig (Standardwerte).
  • !token generate 5 3600 → 5 Nutzungen, 1 Stunde gültig.
• delete <token> → Entfernt ein Token sofort. Beispiel: !token delete ABC123

🧪 Registrierung testen

Zum Test habe ich mir selbst einen Account auf meiner Instanz erstellt.
Konto erstellen → Benutzername, E-Mail, Passwort eingeben → Mail bestätigen → und schließlich den Token eintragen.

Den Token habe ich zuvor im Bot-Raum mit !token generate erzeugt. Nach der Eingabe im Browser war ich direkt eingeloggt – und mein Matrix-Client war einsatzbereit!

✅ Fazit

Mit dieser Kombination aus Synapse-Config und Maubot habe ich endlich eine Lösung, die sowohl sicher als auch bequem ist. Ich kann Registrierungen flexibel freigeben, Tokens mit wenigen Klicks erzeugen und meinen Freunden den Zugang zum Server einfach ermöglichen – ohne meine Instanz zu gefährden.

Das Ganze ist schnell eingerichtet und spart mir auf Dauer jede Menge Ärger.

👥 Techniverse Community

Lust auf Austausch rund um Matrix, Selfhosting und andere smarte IT-Lösungen?
In der Techniverse Community triffst du Gleichgesinnte, kannst Fragen stellen oder einfach nerdigen Talk genießen. 🚀

👉 Jetzt der Gruppe auf Matrix beitreten
~ Direkte Raumadresse: #community:techniverse.net

Wir freuen uns, wenn du dabei bist!